; there are four types of entry in the ZILish adventure description language. they are:
; ROOM blah
; OBJECT blah
; VERB blah
; ROUTINE blah

; the ROOM, OBJECT and VERB entries are all stored in one .txt file called adventure.txt 
; (samples shown below)
; the ROUTINE entries are all stored in a separate .txt file called actions.txt

; unlike the original infocom ZIL, these two files are all you need to make a complete adventure
; they are directly parsed by the ZILish interpreter on the CMM2
; meaning you can edit, update and test your adventures much more efficiently.

; APPLIES TO ALL FOUR ENTRY TYPES:
; every entry begins with a < sign and is immediately followed by the entry type, eg <ROOM or <OBJECT
; then there is a single space and its internal reference name.
; this reference name is never written on screen, it is only used to uniquely identify 
; that particular room/object/verb/routine to the programmer in the game code
; This reference name must be a single word and CANNOT have any spaces in it or it'll confuse the parser - underscores are OK.
; Each reference name must be unique - for example you cannot have two OBJECTs both given the internal reference name "KEY"
; you have to distinguish between them, for example "TRAPDOOR_KEY" and "FRONT_DOOR_KEY"
; likewise, you cannot have two ROOMs given the same internal reference name.
; Remember the player never actually sees this internal reference name.
; each entry declaration is then followed by a number of sub-items, each one contained within normal brackets (.....)
; each sub item is limited by the CMM2 string limit of 256 characters per line
; at the end of all the sub-items, the entry is closed with a >
; then the next entry can begin < etc...
; the entries can appear in any order, you can mix up <ROOM, <OBJECT and <VERB types to your hearts content to aid debugging/readability of the adventure

; ROOM entries
; here is a "normal" game room:

<ROOM LIVING_ROOM
  (FDESC "You are in a brightly lit living room. The walls are custard-yellow and there is an unpleasant smell in the air.")
  (DESC "Living Room")
  (EAST TO KITCHEN)
  (WEST TO STRANGE_PASSAGE IF CYCLOPS_FLED ELSE 'The wooden door is nailed shut.')
  (DOWN PER TRAPDOOR)
  (ACTION LIVING_ROOM_ROUTINE)
  (FLAGS LIGHTSON CYCLOPS_FLED)>

; the spaces before the bracketed items are ignored by the parser,
; they're just there to make reading the ZILish text file easier.

; SUB-ITEMS for a ROOM:
; each ROOM must have an FDESC (full description) -
; this is what is written on the screen the first time the player enters that location.
; each ROOM must also have a DESC (short description) -
; this is what is written on the screen when the player returns to a location he/she has
; already visited previously.
; the exits (if any) need to be added as shown above, one sub-item per exit. Note there don't have to be any exits - 
; there could be a room that you cannot get into or out of by simply walking!
; note that each exit (east, west etc) can be either TO or PER. TO means you walk there (depending on any IF condition)
; PER exits mean there is a door type object that needs to be negotiated to move between the two locations it joins
; note that a door type object doesn't necessary need to be a door - for example, it could be a portal,
; where you have to say a magic word to move between locations.
; the (ACTION) sub-item is a reference to a ROUTINE entry in the actions.txt file that is run just after the player
; has entered the room and it has been describe to them. 
; This could contain conditional things like, "The gear is rotating clockwise" or "The gear is not moving" etc
; (FLAGS) are variable things specific to this room only, for example if the light is on or if a tap is running etc)
; Flags are not variables - they do not contain data, they are either there or not there. If the FLAG is there, it means it is SET.
; If the FLAG is not there, it means it is UNSET. These terms are used in ROUTINES.

<ROOM KITCHEN
  (FDESC "You are in the kitchen. It is beautifully decorated in 1970s brown and tan squares.")
  (DESC "Kitchen")
  (WEST TO LIVING_ROOM)
  (FLAGS LIGHTSON NOTHIEF)>

<ROOM STRANGE_PASSAGE
  (FDESC "You are in a strange, stone passage. Slime is bedraggled down the walls and the floor is damp.")
  (DESC "Strange passage")
  (EAST TO LIVING_ROOM)>

<ROOM BASEMENT
  (FDESC "You are in a dimly lit basement.")
  (DESC "Basement")
  (FLAGS )
  (UP PER TRAPDOOR)>

; there has to be one and only one PLAYER OBJECT in the game. 
; this holds the player's initial location in the game, and how encumbered he/she is
; the internal reference name (the word that follows the <OBJECT declaration) must be PLAYER for the parser to recognise it as the player.

<OBJECT PLAYER
  (LOC LIVING_ROOM)
  (FDESC "Welcome to this adventure game. This is the intro spiel. Yada yada yada. "Go north", "get axe" you know the kind of thing. Good luck!")
  (SIZE 60 0)>

; the player object must have a starting location sub-item, defined in (LOC). This must be an internal room reference name.
; the FDESC holds the introductory waffle to the game. One limitation is that this can only be max 247 characters long
; (256 - (FDESC ) due to the string length limitation of CMM2 BASIC. 
; This is something I'd like to fix in future to allow longer intro spiel
; in the player object, (SIZE) gives two numbers separated by one space - the first is the total amount of stuff they can carry,
; followed by how much they're actually carrying, which starts at 0 but could start at more if you want the player to be carrying
; something when the game begins.

; here is a "normal" game object:

<OBJECT LANTERN
  (FDESC "A battery-powered lantern is on the trophy case.")
  (LDESC "There is a brass lantern here.")
  (DESC "brass lantern")
  (LOC LIVING_ROOM)
  (ACTION LANTERN_ROUTINE)
  (SYNONYM LAMP LANTERN LIGHT)
  (ADJECTIVE BRASS)
  (FLAGS UNLIT)
  (SIZE 15)>

; (FDESC) for OBJECTS is similar to the ROOM entry - it is the full description of the object 
; as it appears in the game before the player has picked it up.
; (LDESC) is a shorter description of the object which is used when the player has just put the object down somewhere.
; (DESC) is the brief description of the object.
; (SYNONYM) is a list of words separated by spaces that the user can type in that will reference this object.
; note that there MUST be at least ONE synonym for each object, otherwise the player will not be able
; to reference it. In the above example, the player could type in lamp, lantern or light, and the interpreter will
; recognise it as the object with the internal name LANTERN
; (ADJECTIVE) are additional words that the player can optionally enter which will distinguish two
; similar objects. For example, there could be a brass key and a large iron key.
; (SIZE) is a measure of how large or heavy something is
; I've set the player's initial max carry at 60, anything over that is too large/heavy to carry
; I've used a size value of 100 to signify something that is fixed in place or impossible to take
; for example, a large carpet or a cupboard attached to a wall.
; (ACTION) is just like in ROOMs, it has a single word following it that references a specific ROUTINE that 
; handles how that object behaves
; (FLAGS) is just like in ROOMs, it is a list of single words that affect variable properties of that object
; for example, if a lamp is on or off. Like ROOMs, OBJECT FLAGS are not variables- they are either SET or UNSET. 

<OBJECT PERSIAN_RUG
  (DESC "Persian rug")
  (FDESC "A rather ornate Persian rug covers most of the middle of the room.")
  (LDESC "The Persian rug is on the floor.")
  (LOC LIVING_ROOM)
  (ACTION PERSIAN_RUG_ROUTINE)
  (SYNONYM RUG CARPET)
  (ADJECTIVE PERSIAN)
  (FLAGS FLAT)
  (SIZE 100)>

<OBJECT TRAPDOOR_KEY
  (SYNONYM KEY)
  (DESC "small rusty key")
  (FDESC "A small rusty key is lying in the dust on the floor.")
  (LDESC "There's a small rusty key here.")
  (LOC STRANGE_PASSAGE)
  (ACTION TRAPDOOR_KEY_ROUTINE)
  (ADJECTIVE SMALL RUSTY)
  (FLAGS )
  (SIZE 1)>

<OBJECT CUPBOARD
  (DESC "cupboard")
  (FDESC "An old wooden cupboard perches precariously on the wall.")
  (LOC KITCHEN)
  (ACTION CUPBOARD_ROUTINE)
  (SYNONYM CUPBOARD)
  (ADJECTIVE WOODEN)
  (FLAGS LOCKED)
  (SIZE 100)>

<OBJECT TRAPDOOR
  (SYNONYM TRAP-DOOR TRAPDOOR)
  (DESC "trapdoor")
  (ACTION TRAPDOOR_ROUTINE)
  (SIZE 100)
  (FLAGS LIVING_ROOM BASEMENT LOCKED)>

; the trapdoor above is a door type object - it connects two locations together.
; note that it doesn't have a (LOC) entry and so does not exist in either of the locations it joins.
; this means that a door object is not described automatically in either location description
; it is simply listed as an exit (north, east etc)
; the two locations connected by the door are given by the first and second items in the FLAGS list of the object.
; note this is the only situation where ROOM objects can appear in a FLAGS list
; there can be more flags afterwards to describe the door object's state (for example LOCKED, OPEN etc),
; but the first two in the FLAGS list MUST be valid ROOM objects (the two locations it connects).

<OBJECT NORTH
  (SYNONYM NORTH N)
  (DESC "to the north")
  (ACTION EXIT)>

; NORTH is given the ACTION type EXIT, defining it as an exit direction type, and it can then be used as a direction of travel
; for moving between ROOMs with " TO " or " PER " - see ROOM description above.
; note exit direction objects don't need a LOC or FDESC
; the DESC simply shows what the interpreter writes on screen when describing visible exits from the current location.

<OBJECT EAST
  (SYNONYM EAST E)
  (DESC "to the east")
  (ACTION EXIT)>

<OBJECT SOUTH
  (SYNONYM SOUTH S)
  (DESC "to the south")
  (ACTION EXIT)>

<OBJECT WEST
  (SYNONYM WEST W)
  (DESC "to the west")
  (ACTION EXIT)>

<OBJECT NORTHWEST
  (SYNONYM NORTHWEST NW N-W)
  (DESC "to the north-west")
  (ACTION EXIT)>

<OBJECT NORTHEAST
  (SYNONYM NORTHEAST NE N-E)
  (DESC "to the north-east")
  (ACTION EXIT)>

<OBJECT SOUTHEAST
  (SYNONYM SOUTHEAST SE S-E)
  (DESC "to the south-east")
  (ACTION EXIT)>

<OBJECT SOUTHWEST
  (SYNONYM SOUTHWEST SW S-W)
  (DESC "to the south-west")
  (ACTION EXIT)>

<OBJECT DOWN
  (SYNONYM DOWN D)
  (DESC "down")
  (ACTION EXIT)>

<OBJECT UP
  (SYNONYM UP U)
  (DESC "up")
  (ACTION EXIT)>

<OBJECT PLUGH
  (SYNONYM PLUGH)
  (LOC NONE)>

; if an object has a LOC of "NONE" this means the object doesn't physically exist in the world.
; if can be used to "disappear" objects, for example, some food after it's been eaten, or
; like the above, a word that someone can say

<OBJECT ON
  (SYNONYM ON)
  (LOC NONE)>

<OBJECT OFF
  (SYNONYM OFF)
  (LOC NONE)>


; VERB types are the simplest entries.
; they need only SYNONYNM and ACTION sub-items

<VERB EAT
  (SYNONYM EAT MUNCH CONSUME)
  (ACTION EAT_ROUTINE)>

<VERB OPEN
  (SYNONYM OPEN)
  (ACTION OPEN_ROUTINE)>

<VERB CLOSE
  (SYNONYM CLOSE SHUT)
  (ACTION CLOSE_ROUTINE)>

<VERB LOCK
  (SYNONYM LOCK)
  (ACTION LOCK_UNLOCK_ROUTINE)>

<VERB UNLOCK
  (SYNONYM UNLOCK)
  (ACTION LOCK_UNLOCK_ROUTINE)>

<VERB SWITCH
  (SYNONYM TURN SWITCH)
  (ACTION SWITCH_ROUTINE)>

<VERB GET
  (SYNONYM GET PICK TAKE)
  (ACTION GET_ROUTINE)>

<VERB DROP
  (SYNONYM DROP)
  (ACTION DROP_ROUTINE)>

<VERB INVENTORY
  (SYNONYM INV INVENTORY CARRYING)
  (ACTION INVENTORY_ROUTINE)>

EOF!

; the file must conclude with EOF! followed by carriage return (enter key)
; the interpreter looks for this character combination to know it has reached
; the end of the file and it needn't read any more.
